home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / 051-060 / amok52 / headerinfo < prev    next >
Text File  |  1993-11-04  |  12KB  |  335 lines
  1. ======================================================================
  2.            AMOK - AMIGA Modula & Oberon Klub  Stuttgart
  3.  
  4.                  Standard Identifier für ProgInfo
  5.            (Dokumentationsextraktion aus dem Quelltext)
  6. ======================================================================
  7.  
  8.  
  9. Programmkopf
  10.  
  11. Für alle AMOK-Programme ist ein Programmkopf vorgeschrieben, der die
  12. wichtigsten Informationen zu diesem enthält.
  13. Bei Modula-2- bzw. Oberon-Programmen muß er vor dem Schlüsselwort MODULE
  14. in einem Kommentar stehen. Er sollte durch "***"- oder "---"-Zeilen
  15. hervorgehoben sein, ein Einrahmen ist jedoch nicht zweckmäßig (da die
  16. letzten "*"s in der Zeile stören).
  17. Der Programmkopf enthält mehrere Einträge, die jeweils mit
  18. ":"Schlüsselwort"." beginnen. Reicht eine Zeile für einen Eintrag nicht
  19. aus, wird das ":"Schlüsselwort"." in der nächsten Zeile wiederholt und
  20. der Eintrag danach fortgesetzt. Doppelpunkt, Punkt und Schreibweise
  21. sind wichtig, da sonst die Einträge von Doku-Extraktionsprogrammen nicht
  22. gefunden werden.
  23.  
  24. Der Programmkopf muß (!) mindestens folgende Einträge enthalten:
  25.  
  26. :Program.       <Programmname>
  27. :Contents.      <Kurzbeschreibung von Inhalt/Verwendungszweck>
  28. :Author.        <voller Autorenname, kein Pseudonym (!)>
  29. :Copyright.     <Bemerkung über Copyright>
  30. :Language.      <Sprache, eventuell Bemerkung über Besonderheiten>
  31. :Translator.    <Name des Compilers/Assemblers mit Versionsangabe>
  32. :History.       <Version, Autor, Datum, Bemerkung>
  33.  
  34. Falls notwendig müssen auch folgende Angaben gemacht werden:
  35.  
  36. :Support.       <Hinweis auf von anderen übernommene Programmteile/Ideen>
  37. :Imports.       <Importierte Module außer dem Standardumfang des Compilers>
  38. :Bugs.          <bekannte Fehler>
  39.  
  40. Freiwillig sind diese Angaben:
  41.  
  42. :Address.       <Adresse des Autors>
  43. :Phone.         <seine Telephonnummer>
  44. :Update.        <Angaben über Änderungen, die :History. nicht abdeckt>
  45. :Remark.        <beliebiger Kommentar>
  46. :Usage.         <Usage zB. für CLI-Befehl>
  47.  
  48. Andere Einträge Date, Shortcut, Version sind möglichst nicht mehr zu
  49. benutzen! Fehlende Einträge sollten so bald und gut als möglich
  50. nachgetragen oder rekonstruiert werden.
  51.  
  52.  
  53. Empfehlungen
  54.  
  55. Auf eine strikte Festlegung des Programmkopftextes wurde verzichtet. Damit
  56. dieser jedoch einigermaßen einheitlich bleibt sollte man die folgenden
  57. Regeln beachten.
  58.  
  59. Leere Einträge
  60.  
  61. Außer den zuerst genannten Pflichteinträgen können eventuell auch welche
  62. entfallen. Am besten läßt man dann den gesammten Eintrag sammt Schlüssel-
  63. wort weg. Als leer gelten außerdem Einträge, die nur aus Leerzeichen,
  64. Sternchen "*" oder Strichen "-" bestehen.
  65. Unsinnige Einträge (zB. ":Imports. bis jetzt noch nichts") sind möglichst
  66. zu unterlassen.
  67.  
  68. :Program.
  69.  
  70. Hier sollte der Programmname stehen, der mit dem Filenamen (mit Extension,
  71. zB. "Test.def") übereinstimmen sollte. Reicht der Programmname zur
  72. eindeutigen Indentifizierung nicht aus (zB. geändertes Modul "Strings")
  73. so steht hinter dem Programmnamen ein entsprechender Kommentar.
  74.  
  75. :Contents.
  76.  
  77. Kurzbeschreibung von Programminhalt und -funktion. Die Beschreibung
  78. sollte erklärend sein und nicht nur eine längere Version des Programm-
  79. namens sein (zB.  N I C H T :
  80.  :Program.  InOut.def
  81.  :Contents. Definitionsmodul Input/Output
  82. ).
  83.  
  84. :Author.
  85.  
  86. Bitte den vollen Namen angeben. Pseudonyme sind unzulässig.
  87. Ein Programm kann auch mehere Autoren haben, zB. wenn ein PC-Programm
  88. auf den AMIGA umgesetzt wurde.
  89.  
  90. :Address.
  91.  
  92. Freiwillig ist die Angabe der Adresse des Autors. Sie sollte Straße,
  93. Hausnummer, Postleitzahl, Ort und Land enthalten.
  94.  
  95. :Phone.
  96.  
  97. Telefonnummer des Autors mit Vorwahl. Zusätzliche Bemerkungen, zB. Zeit-
  98. angaben für Erreichbarkeit, sind zulässig. Hat ein Programm mehere Autoren
  99. (s. oben) so steht hier die Telefonnummer des für dieses Programm
  100. zuständigen Autors, d.h. desjenigen, der eventuelle Fragen am besten
  101. beantworten kann.
  102.  
  103. :Copyright.
  104.  
  105. Hieraus sollte ersichtlich sein, ob das Programm ShareWare oder FreeWare ist.
  106. Ausserdem kann man natürlich auch den Ueberbegriff PD (Public Domain)
  107. benutzen, man sollte aber dann im Dok-File die Kopierbestimmungen festlegen.
  108. ShareWare: - Der Autor legt die Kopierbestimmungen fest
  109.            - Bei regelmäßigem Gebrauch wird eine anerkennende Gebühr
  110.              (ShareWare-Gebühr) erwartet, die gezahlt werden MUSS!
  111.  
  112. FreeWare: - Der Autor legt die Kopierbestimmungen fest und behält
  113.             alle Rechte an seinem Programm
  114.  
  115. Kommentare wie zB. "copy it, but leave my name in" oder ähnliches sind
  116. zulässig. Bei längeren "Plädoyers" sollte allerdings auf eine extra
  117. Datei verwiesen werden.
  118.  
  119. :Language.
  120.  
  121. Hier steht im Normalfall "Modula-2" bzw. "Oberon". Wenn das Programm
  122. INLINE-Assemblercode enthält, sollte dies hier Vermerkt werden. Ebenso
  123. sollte verfahren werden, wenn das Programm dem Modula-Standard nicht
  124. entsprechende Statements enthält. Dazu gehört unter anderem die seit
  125. M2Amiga v3.2 mögliche Typenkonversion von ADDRESS/BPTR und die
  126. Dereferenzierung von BPTRn (Zugriff auf BcplPtr^.items). Die normale
  127. Verwendung des Typs BPTR als opaker Typ gehört nicht dazu, denn er ist
  128. im Standard-Modula erlaubt.
  129. Der Sinn hiervon ist es, Leute zu warnen, die Programme auf andere
  130. Compiler umsetzen wollen.
  131.  
  132. :Translator.
  133.  
  134. Bezeichnet den Compiler (/Assembler/Interpreter) und die Versionsnummer
  135. (V3.2d oder V3.1d). Dahinter stehen eventuelle Hinweise auf Compiler-Bugs,
  136. die für dieses Programm relevant sind.
  137.  
  138. :History.
  139.  
  140. Dies ist einer der wichtigsten Einträge. Er beinhaltet Informationen
  141. über die Versionen des Programms (Opfer), der entsprechenden
  142. Erstellungs- und Änderungsdaten (Tatzeit), den Autor oder für die
  143. Änderung Veratwortlichen (Täter) sowie eine optionale Bemerkung
  144. (Motiv). Beispiel:
  145.  
  146. :History.       v1.1 [bne] 29-Mar-89 bug in Init() fixed
  147.  
  148. Den Versionsnummern wird später noch ein spezielles Kapitel gewidmet.
  149. Zusammengehörige Definitions- und Implementationsmodule tragen immer
  150. mindestens gleiche Versionsnummer (Revisionsnummer, Branchnummer und
  151. Kennbuchstabe dürfen verschieden sein).
  152. Das Datum besteht aus dem ein- oder zweistelligen Tag, dem Monats-
  153. kürzel (Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dez) aus drei
  154. Buchstaben und der zwei oder vierstelligen Jahreszahl. Für den Autor
  155. steht sein Name in []-Klammern (für Klubmitglieder das Kürzel).
  156.  
  157. :Support.
  158.  
  159. Der Fairneß halber sollte man hier Angaben über Beiträge anderer
  160. Personen sowie deren Namen machen, wenn man Schuldgefühle wegen
  161. geklauter Ideen oder Algorithmen hat.
  162.  
  163. :Imports.
  164.  
  165. Importiert das Modul außer den Standardmodulen des Compilers noch
  166. weitere, so müssen diese hier eingetragen werden. Wird eine bestimmte
  167. Version benötigt, folgt auf den Namen des importierten Moduls dessen
  168. Versionsnummer sowie der Autor. Es dürfen auch Verweise auf AMOK-Disks
  169. gemacht wedren. Beispiel:
  170.  
  171. :Imports.       MemSystem1.3 [bne], List [mif] AMOK#7
  172.  
  173. :Bugs.
  174.  
  175. Sind Fehler eines Moduls bekannt, oder besteht der Verdacht, daß das
  176. Modul fehlerhaft ist, wird dies hier vermerkt. Soweit dies möglich
  177. ist, soll der Fehler möglichst eng eingegrenzt werden (zB Angabe der
  178. Prozedur, in der er auftritt). Ist ein Modul noch nicht vollständig
  179. ausgetestet, sollte man mit ":Bugs. not tested" warnen. ":Bugs. none"
  180. verpflichtet zu mindestens 99,9% Fehlerfreiheit!
  181.  
  182. :Usage.
  183.  
  184. bezeichnet die Syntax eines CLI-Befehls und dessen Argumente.
  185. Die Usage wird entweder in EBNF oder mit dem vom DOS-Handbuch und
  186. ARP verwendeten Template angegeben.
  187.  
  188.  
  189. Versionsnummern
  190.  
  191. Die Versionsnummer besteht normalerweise aus zwei Stellen (version,
  192. revision), die durch einen Punkt getrennt sind. Die erste lauffähige
  193. Version wird mit 1.0 bezeichnet. Bei jeder Änderung wird die zweite Stelle
  194. (Revision) um eins erhöht, wobei nach 1.9 die 1.10 und dann 1.11 usw.
  195. folgt. Bei sehr tiefgreifenden Neuerungen wird die erste Stelle (Version)
  196. erhöht, die zweite (Revision) springt auf 0. Die Versionsnummer darf
  197. NICHT als Dezimalbruch angesehen werden, der sich jedesmal um 1/10 erhöht.
  198. Eine Revision ist KEINE zehntel Version und eine Version entspricht
  199. NICHT 10 Revisions. Version und Revision werden unabhängig gezählt!!!
  200. Versionsnummern wie 1.09 sind unzulässig und 1.10 (erste Version, zehnte
  201. Revision) steht zwischen 1.9 und 1.11 und ist nicht gleich 1.1 !
  202. "Hundertstel" Versionen gibt es nicht. Wenn es erforderlich wird, eine
  203. Version nachträglich in eine Reihe einzufügen, wird dies durch eine zweiten
  204. Punkt gekennzeichnet. Beispiel:Es existieren bereits die Versionen 1.0 bis
  205. 1.4 , und jemand ändert nachträglich die Version 1.2  . Diese bekommt dann
  206. die Nummer 1.2.1 (sog. Branch-Version). Man kann Versionsreihen auch als
  207. Baum darstellen:
  208.  
  209.       1.0
  210.  
  211.        |
  212.        V
  213.  
  214.       1.1
  215.  
  216.        |
  217.        V
  218.  
  219.       1.2
  220.  
  221.        |
  222.       / \
  223.      /   \
  224.     V     V
  225.  
  226.    1.3   1.2.1
  227.  
  228.     |      |
  229.     V      V
  230.  
  231.    1.4    1.2.2
  232.  
  233.     |      usw.
  234.  
  235.    ...
  236.  
  237.     |
  238.     V
  239.  
  240.    1.9
  241.  
  242.     |
  243.     V
  244.  
  245.    1.10
  246.  
  247.    usw.
  248.  
  249.  
  250. Die Zählweise entspricht nicht der von Big Blue, verleitet aber dafür zu
  251. weniger Mißverständnissen, weil man nicht rätseln muß, ob 3.2 jetzt die auf
  252. 3.1 oder auf 3.19 folgende Version ist. Version und Revision können
  253. beliebig hoch werden - Beispiel: die Libraries der alten 1.2 Workbench
  254. trugen die Versionsnummer 33.180 (dreiunddreißigste Version,
  255. hundertachzigste Revision).
  256.  
  257. Wer noch eine feiner abgestufte Unterscheidung machen möchte, kann der
  258. Nummer noch einen Kleinbuchstaben anhängen. Dieser ist optional und muß
  259. nichts über die Reihenfolge aussagen (zB. 3.2d für die deutsche und 3.2e
  260. für die englische Version).
  261.  
  262. Entsprechend dem Vorschlag von Bernd Preusing ist es jetzt doch zulässig,
  263. daß ein Implementationsmodul eine höhere Revisionsnummer hat wie das
  264. zugehörige Definitionsmodul. Dadurch ist es nicht nötig, wegen jeder
  265. Kleinigkeit das Definitionsmodul anzutasten, wodurch das Make viel Arbeit
  266. bekäme.
  267.  
  268.  
  269. Source-Code-Format
  270.  
  271. Damit der Sourcecode einigermaßen übersichtlich ist, wird folgende
  272. Formatierung vorgeschlagen (nicht zwingend, nur übersichtlich muß es sein):
  273.  
  274. * In jeder Zeile steht nur eine logische Anweisungseinheit.
  275.  
  276. * Globale Prozeduren, Variablen und Konstanten stehen ganz am Anfang
  277.   der Zeile.
  278.  
  279. * Deklarationen und Prozedurkörper sind gegenüber ihrem CONST, VAR,
  280.   TYPE und PROCEDURE eingerückt.
  281.  
  282. * Programmteile, die lokal zu anderen definiert werden, oder von
  283.   bestimmten Konstrukten eingeschlossen werden, werden jeweils
  284.   relativ zu diesen um ZWEI Zeichen eingerückt.
  285.  
  286. * Zusammengehörende BEGIN und END, IF, ELSE und END usw. stehen jeweils
  287.   untereinander. Ist ein END mehr als eine Bildschirmseite (25 Zeilen)
  288.   von seinem BEGIN etc. entfernt, steht hinter dem END in Kommentar,
  289.   was dort beendet wurde.
  290.  
  291. * Außer nach VAR, CONST, TYPE, BEGIN, DO, THEN, LOOP, RETURN und EXIT
  292.   steht hinter jeder Zeile ein Semikolon.
  293.  
  294. * Elemente von Mengen, Aufzählungstypen und RECORDs fangen klein an,
  295.   Konstanten fangen klein oder groß an, alles andere immer groß.
  296.   Zusammengesetzte Wörter haben auch in der Mitte "GrossBuchstaben".
  297.  
  298. * Paßt die Parameterliste einer Prozedur nicht in eine Zeile
  299.   (75 Zeichen), werden die Parameter untereinander angeordnet.
  300.  
  301. * Importe werden alphabetisch nach den Namen der Module geordnet.
  302.   Sind Importlisten länger als zwei Zeilen werden auch die importierten
  303.   Objekte alphabetisch sortiert.
  304.  
  305. MODULE Beispiel;
  306.  
  307. CONST
  308.   welches = 106;
  309.  
  310.  
  311. PROCEDURE TuWas(    Dies : Typ;
  312.                 VAR Jenes : Art) : BOOLEAN;
  313.   CONST
  314.     X = 1;
  315.     Y = 10;
  316.  
  317.   VAR
  318.     Zähler : INTEGER;
  319.  
  320.   BEGIN
  321.     FOR Zähler := X TO Y DO
  322.       Action(Dies, Jenes);
  323.     END
  324.     RETURN Jenes = welches
  325.   END TuWas;
  326.  
  327.  
  328. BEGIN
  329.   IF TuWas(etwas, irgendWas) THEN
  330.     Aktion1;
  331.   ELSE
  332.     Aktion2;
  333.   END;
  334. END Beispiel.
  335.